ContentConnect

For Salesforce Commerce Cloud

e-Spirit AG

FirstSpirit Version 5.x

17.02.2017
Inhaltsverzeichnis

1. Einleitung

FirstSpirit dient der Erstellung vielseitiger und projektspezifischer Inhalte. Mit ContentConnect wurde die Möglichkeit geschaffen, diese Inhalte in das E-Commerce-Shopsystem Salesforce Commerce Cloud zu übertragen und dort zu nutzen.

Im restlichen Dokument wird anstelle “Salesforce Commerce Cloud” die Kurzform “Commerce Cloud” benutzt. Damit ist immer ausschließlich die Salesforce Commerce Cloud gemeint.

Es kombiniert die funktionalen Stärken beider Systeme, um so die besten Vorteile zu erzielen und ein erfolgreiches Gesamtsystem zu schaffen. Dieses Gesamtsystem besteht aus zwei Bereichen, die parallel und größtenteils entkoppelt voneinander arbeiten:

FirstSpirit-seitige Komponenten
Diese Komponenten dienen der Erstellung und Pflege der redaktionellen Daten. Diese werden in Form von XML-Dateien und Medien an die Commerce Cloud übermittelt.
Commerce Cloud-seitige Komponenten
Diese Komponenten dienen der Verarbeitung der in FirstSpirit erstellten redaktionellen Inhalte. Die Commerce Cloud integriert diese Daten in das hinterlegte HTML-Gerüst und überführt sie mit diesem in den Live-Stand.

Dieses Dokument bezieht sich lediglich auf die FirstSpirit-seitigen Komponenten. Es wird vorausgesetzt, dass der Leser mit der Commerce Cloud vertraut und sicher in dessen Verwendung ist.

1.1. Funktionsumfang

ContentConnect stellt Redakteuren die folgenden Möglichkeiten zur Verfügung:

  • Erstellung nativer Commerce Cloud-Inhalte mit FirstSpirit
  • Zugriff auf Produktinformationen über die Open Commerce API (OC API)
  • gleichzeitige Darstellung von Shop-Elementen und redaktionellen Inhalten in der Vorschau
  • Übertragung von Inhalten in den Commerce Cloud Storage über WebDAV

Die entsprechenden Funktionalitäten werden mit der Installation und Konfiguration der Module sowohl im SiteArchitect als auch im ContentCreator bereitgestellt.

Die Pflege der Inhalte findet über die gewohnten FirstSpirit-Mittel statt. Mit FirstSpirit vertraute Redakteure benötigen daher keine darüber hinausgehenden Kenntnisse. Die Inhalte werden im Rahmen eines Deployments der Commerce Cloud zum Import bereitgestellt. Diese überträgt die Informationen in den Live-Stand.

Die Auslieferung erzeugt somit keinen Unterschied für die Commerce Cloud und ist unabhängig von der Erreichbarkeit des FirstSpirit-Servers. Auch wenn dieser beispielsweise aufgrund von Wartungsarbeiten heruntergefahren wird, beeinflusst dies die Commerce Cloud und damit die Auslieferung der deployten Inhalte nicht.

1.2. Architektur

Die Verbindung von FirstSpirit und der Commerce Cloud wird über eine Architektur aus verschiedenen Komponenten realisiert (vgl. Abbildung Architektur). Diese Komponenten sind:

  • die auf dem FirstSpirit-Server installierten Module:

    • ContentConnect-Modul
    • WebDAV-Modul
    • JSTL-Modul
  • Commerce Cloud-Instanzen (Staging & Production)
Architektur
Abbildung 1. Architektur


Das Zusammenspiel der einzelnen Komponenten erfolgt immer nach dem folgenden Schema:

  1. Die Erstellung und Bearbeitung der redaktionellen Inhalte findet FirstSpirit-seitig statt. Die Inhalte ersetzen Platzhalter im HTML-Gerüst, das ebenso wie die auf der Live-Seite angezeigten Produkte jedoch aus der Commerce Cloud stammt. Es wird per http nach FirstSpirit übertragen, wo es für die vollständige Darstellung der Vorschau benötigt wird. Die Übergabe der Produkte nach FirstSpirit erfolgt über die OC API-Schnittstelle der Commerce Cloud Staging Instanz.
  2. Alle in FirstSpirit vorgenommenen inhaltlichen Änderungen werden im Rahmen eines Deployments per WebDAV der Commerce Cloud Staging Instanz bereitgestellt. Sie werden in Form von Medien und XML-Dateien in verschiedenen WebDAV-Verzeichnissen abgelegt. Von dort werden sie über Jobs in die Library der Commerce Cloud Staging Instanz importiert.
  3. Diese Library wird zusammen mit dem Produktkatalog auf die produktive Commerce Cloud Instanz repliziert. Für die Commerce Cloud ergibt sich somit bei der Auslieferung redaktioneller Inhalte in den Live-Stand keinerlei Unterschied.

Die Commerce Cloud stellt somit die Hauptkomponente dieser Architektur dar. Es liefert die in FirstSpirit erstellten bzw. gepflegten Inhalte an die Kunden aus und stellt sämtliche Shop-Funktionalitäten zur Verfügung. Zwischen beiden Systemen existiert lediglich eine lose Kopplung. Sie arbeiten hauptsächlich parallel zueinander. Wird der FirstSpirit-Server beispielsweise aufgrund von Wartungsarbeiten heruntergefahren, beeinflusst dies die Commerce Cloud nicht.

1.3. Technische Voraussetzungen

ContentConnect besitzt die folgenden technischen Voraussetzungen:

  • FirstSpirit-Version: FirstSpirit 5.1 (oder höher)
  • E-Commerce-Shopsystem Commerce Cloud
  • Open Commerce API in der Version 16.9
  • Apache Commons Codec 1.8
  • aktuelle JSTL-Version (Diese wird mit dem JSTL-Modul bereitgestellt.)
  • Java 8

Für die fehlerfreie Arbeit mit der Commerce Cloud benötigt der FirstSpirit-Server Java 8. Ist die Verwendung der Java-Version 7 gewünscht, müssen entsprechende Anpassungen in der fs-wrapper.conf vorgenommen werden.

Für die fehlerfreie Darstellung der Vorschau des mitgelieferten Beispielprojekts, muss Chrome verwendet werden. Dieser kann im Menü des SiteArchitects unter AnsichtBrowser EngineGoogle Chrome ausgewählt werden.

1.4. Wichtige Hinweise

Dieses Kapitel enthält Hinweise, die bei der Verwendung des ContentConnect-Moduls zu beachten sind.

1.4.1. Content Asset ID

Content Assets, die in FirstSpirit angelegt werden, bekommen von FirstSpirit eine eindeutige ID. Wird in der Commerce Cloud ein Content Asset mit exakt derselben ID angelegt, wird dieses beim Veröffentlichen von FirstSpirit überschrieben.

2. Komponenten

ContentConnect besteht aus verschiedenen Komponenten. Die Funktionalität dieser Komponenten wird in den nachfolgenden Unterkapiteln erläutert.

2.1. ContentConnect-Modul

Das ContentConnect-Modul ist die Hauptkomponente der Verbindung zwischen FirstSpirit und der Commerce Cloud. Es hat eine maßgebliche Bedeutung für den bidirektionalen Datenaustausch zwischen dem FirstSpirit-Server und der Commerce Cloud.

Sowohl im SiteArchitect als auch im ContentCreator wird durch das Modul ein Report bereitgestellt. Dieser Report dient der Darstellung der Produktinformationen aus der Commerce Cloud. Stößt ein Redakteur eine entsprechende Abfrage an, ermittelt das Modul die gewünschten Daten und übergibt sie dem Report. Die zurückgelieferten Daten können anschließend für die Erstellung und Pflege redaktioneller Inhalte weiterverwendet werden.

Wird nach der Erstellung der Inhalte eine Generierung ausgeführt, fasst das Modul sie in Form zweier XML-Dateien zusammen. Die Dateien werden dann vom WebDAV-Modul in den Commerce Cloud Storage übermittelt. Aus diesem liest die Commerce Cloud die Daten aus und überträgt sie in den Live-Stand.

Das ContentConnect-Modul stellt eine API bereit, mit der projektspezifische Funktionalitäten implementiert werden können. Weitere Informationen können der mitgelieferten Javadoc-Dokumentation entnommen werden.

2.2. WebDAV-Modul

Die Erstellung und Bearbeitung der redaktionellen Inhalte findet FirstSpirit-seitig statt. Ihre Übertragung in den Live-Stand erfolgt hingegen durch die Commerce Cloud. Ihm müssen die Inhalte daher bereitgestellt werden. Dafür erstellt das ContentConnect-Modul im Rahmen eines Deployments jeweils eine XML-Datei für die Library und die Slot Configuration. Sie müssen zusammen mit den referenzierten Medien an die Commerce Cloud übergeben werden.

Diese Aufgabe übernimmt das WebDAV-Modul. Es fungiert als Bindeglied zwischen FirstSpirit und der Commerce Cloud und legt die Daten im Commerce Cloud Storage ab. Aus diesem werden sie von der Commerce Cloud ausgelesen.

2.3. JSTL-Modul

Im SiteArchitect ist innerhalb des Templatecodes die Möglichkeit zur Verwendung von JSTL-Tags erforderlich. Diese Möglichkeit stellt das JSTL-Modul bereit. Es muss jedoch nur dann auf dem FirstSpirit-Server installiert werden, wenn JSTL noch nicht anderweitig auf dem Server eingebunden ist.

2.4. Commerce Cloud Cartridge

Die Cartridge int_firstspirit_cms bietet Funktionen zum Import der in FirstSpirit erstellten redaktionellen Inhalte in die Commerce Cloud. Hierzu enthält sie die Pipeline ContentSync, die wiederum zwei Startknoten besitzt: LIBRARY und SLOT_CONFIGURATIONS (vgl. Abbildung Pipeline Content Sync). Über LIBRARY werden die redaktionellen Inhalte importiert. Die Slot-Konfigurationen entsprechend über SLOT_CONFIGURATIONS. Für beide Fälle erwartet die Pipeline die Parameter ImportFile und ImportMode. Der Aufruf der Pipeline sollte über Job Schedules geschehen (vgl. Einrichtung der Job Schedules)

Pipeline Content Sync
Abbildung 2. Pipeline Content Sync


Außerdem enthält die Cartridge den JavaScript Controller RenderTemplate. Dieser wird benötigt, um das Mapping von Commerce Cloud Render Templates auf FirstSpirit Seitenvorlagen zu realisieren und damit das Anlegen von Detailseiten zu ermöglichen (vgl. Product Page Template Uid, Category Page Template Uid und Detailseiten).

3. Installation und Konfiguration

Für die Verwendung der ContentConnect-Funktionalitäten ist die Installation und Konfiguration unterschiedlicher FirstSpirit- und Commerce Cloud-Komponenten notwendig.

3.1. FirstSpirit

In den folgenden Unterkapiteln wird zunächst die Installation und Konfiguration der FirstSpirit-seitigen Komponenten erläutert.

3.1.1. Installation der Module

Die ContentConnect-Auslieferung enthält drei Module, die auf dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie für die Installation der Module den ServerManager und wählen Sie den Bereich Server-EigenschaftenModule.

Modulverwaltung in den Server-Eigenschaften
Abbildung 3. Modulverwaltung in den Server-Eigenschaften


Im Hauptpanel ist eine Liste aller auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren nacheinander zunächst die mitgelieferte contentconnect-fsm-<Versionsnummer>.fsm und anschließend die WebDavDeployment-<Versionsnummer>.fsm sowie die jstl.fsm aus. Bestätigen Sie die Auswahl jeweils mit Öffnen. Nach der erfolgreichen Installation wurden der Liste die Ordner ContentConnect, WebDavDeployment und JSTL hinzugefügt, von denen jeder Alle Rechte erhalten muss.

Das JSTL-Modul muss nur dann installiert werden, wenn JSTL noch nicht anderweitig auf dem Server eingebunden ist.

Nach jeder Installation oder Aktualisierung eines Moduls ist ein Neustart des FirstSpirit-Servers notwendig.

3.1.2. Apache Commons Codec 1.8

Die Installation der Module muss anschließend durch die Ergänzung des Apache Commons Codec in der Version 1.8 vervollständigt werden. Dabei handelt es sich um eine Bibliothek, die vom WebDAV-Modul verwendet wird.

Sie benötigen das Archiv commons-codec-1.8-bin.zip, welches Sie unter der folgenden URL herunterladen können: http://commons.apache.org/proper/commons-codec

Extrahieren Sie die Datei an einer beliebigen Stelle innerhalb ihres Dateisystems und separieren Sie das commons-codec-1.8.jar. Diese jar-Datei muss dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie dafür das Verzeichnis Ihrer FirstSpirit-Installation, wechseln Sie in den Unterordner sharedlib und kopieren Sie die jar-Datei hinein.

Der FirstSpirit-Server muss im Anschluss neugestartet werden.

3.1.3. WebDAV-Verwendung mit https

Um den WebDAV-Server mit https statt http zu verwenden, ist allgemein keine zusätzliche Konfiguration notwendig. Für https wird jedoch im Allgemeinen eine lokale vom Unternehmen verwaltete Zertifizierungsstelle verwendet. Dessen Zertifikat muss inklusive der gesamten Kette bis zum Zertifikat des WebDAV-Servers der JVM des FirstSpirit-Servers zur Verfügung gestellt werden.

Die JVM erwartet diese öffentlichen Zertifikate als PKCS12- oder JKS-Datei.

Importieren Sie die öffentlichen Root- oder Zwischenzertifikate über das folgende Kommando in eine JKS-Datei und beantworten Sie die Frage, ob dem Zertifikat vertraut werden soll, mit Ja. Dieser Vorgang muss für jedes Zertifikat wiederholt werden.

keytool -import -file cert1.crt -keystore truststore.jks –storepass changeit

Kopieren Sie den erzeugten Trust Store in das Verzeichnis firstspirit5conf ihres FirstSpirit-Servers und fügen Sie die folgenden Zeilen der Datei firstspirit5conffs-wrapper.conf hinzu.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

Die Parameter müssen über einen Neustart des FirstSpirit-Servers aktiviert werden.

Sollte der WebDAV-Server eine wechselseitige SSL-Authentifizierung erwarten, muss über die folgenden Aufrufe zunächst ein Client-Zertifikat erstellt und signiert werden.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

Die Datei request.csr wird an die Zertifizierungsstelle versandt, die mit der Datei cert.crt antwortet. Der private Schlüssel, das öffentliche Zertifikat und das Zertifikat der Zertifizierungsstelle müssen anschließend in einem von der JVM zu lesenden Key Store zusammengefasst werden.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

Falls die Zertifikatskette aus einem oder mehreren Zwischenzertifikaten besteht, können diese via keytool importiert werden.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

Der Key Store lässt sich über das Hinzufügen der folgenden Zeilen in die firstspirit5conffs-wrapper.conf an die JVM des FirstSpirit-Servers übergeben.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

3.1.4. Konfiguration der Projekt-Komponente

Für den Einsatz des ContentConnect-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem verwendeten Projekt hinzuzufügen ist. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenProjekt-Komponenten.

Projekt-Komponenten in den Projekt-Eigenschaften
Abbildung 4. Projekt-Komponenten in den Projekt-Eigenschaften


Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Wählen Sie nach dem Klicken auf Hinzufügen die ContentConnect Project Configuration und bestätigen Sie die Auswahl mit OK. Die Projekt-Komponente wird anschließend der Liste im Hauptpanel hinzugefügt und muss anschließend noch konfiguriert werden (vgl. Abbildung Projekt-Komponenten in den Projekt-Eigenschaften). Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren (vgl. Abbildung Konfigurationsdialog der Projekt-Komponente).

Konfigurationsdialog der Projekt-Komponente
Abbildung 5. Konfigurationsdialog der Projekt-Komponente


Base URL
In dem Dialog wird zunächst die Base URL erfasst, die sich aus der URL der Commerce Cloud-Instanz und der ID der verwendeten Site ergibt:

https://<SUBDOMAIN INSTANCE>.demandware.net/s/<SITE ID>

Basierend auf dieser Struktur ist stets eine eindeutige Verbindung zwischen dem FirstSpirit-Projekt und der Commerce Cloud-Site sichergestellt. Bei der Base URL handelt es sich um ein Pflichtfeld.
Client ID
Anschließend ist die Client ID anzugeben, die zur Verwendung der Open Commerce Shop API benötigt wird und deshalb ebenfalls eine Pflichtangabe ist.

Die Client ID und die Base URL sind für die Verbindung zwischen der Commerce Cloud und FirstSpirit zwingend erforderlich. Ist eine der beiden Angaben fehlerhaft oder gar nicht erst vorhanden, wird der jeweilige Report für die Produktsuche in beiden FirstSpirit-Clients ausgeblendet.

Password
Einige Komponenten der ContentConnect-API erfordern eine passwortbasierte Authentifizierung gegenüber der Commerce Cloud , bei der die Angabe der Client ID nicht ausreichend ist. Dazu gehören z.B. die Interfaces LibraryManager und SlotConfigurationManager. Falls eine solche Schnittstelle verwendet wird, muss in diesem Konfigurationsfeld ein Passwort hinterlegt werden, andernfalls kann das Feld leer bleiben. Das einzutragende Passwort wird wie die Client ID während der Registrierung der Client-Applikation bei der Commerce Cloud erzeugt.
Refinements
In diesem Konfigurationsfeld lassen sich Refinements definieren, die zur Verfeinerung der Produktsuche genutzt werden. Die Refinements sind als kommaseparierte Liste von Schlüssel-Wert-Paaren anzugeben.

Es werden maximal die ersten neun angegebenen Schlüssel-Wert-Paare genutzt, da die Commerce Cloud nicht mehr als neun Refinements akzeptiert.

Das Format der Werte der Schlüssel-Wert-Paare entspricht dem von der Commerce Cloud erwarteten Format für Refinement-Werte. Es können also mehrere Werte sowie Wertmengen für ein Refinement angegeben werden:

  • cgid=new-arrivals|electronics
  • price=(0..100)

Die Filterung nach einer Kategorie geschieht ebenfalls über ein Refinement, weshalb zwei Sonderfälle zu beachten sind:

Im ersten Fall

  • wird in der Produktsuche nach einer Kategorie gefiltert und
  • die Konfiguration enthält neun Refinement-Definitionen,
  • von denen keine das Kategorie-Refinement cgid ist.

In diesem Fall liegen insgesamt zehn Refinement-Definitionen vor, was unzulässig ist. Deshalb wird ein Refinement aus der Konfiguration ignoriert, um stattdessen die Kategorie-Filterung zu ermöglich.

Im zweiten Fall

  • wird in der Produktsuche ebenfalls nach einer Kategorie gefiltert und
  • die Konfiguration enthält das Kategorie-Refinement cgid.

In diesem Fall gibt es eine doppelte Definition für das Kategorie-Refinement cgid: eine aus der Modulkonfiguration und eine aus der Produktsuche, wobei letztere verwendet wird. Der Wert aus der Konfiguration dient dann als Default-Wert und kann vom Redakteur überschrieben werden.

Locale
Über dieses Konfigurationsfeld lässt sich der Sprachkontext des aktuellen Projektes angeben. Erlaubt ist die Angabe maximal einer Id einer aktiven Locale, die für Storefront-Anfragen in der oben konfigurierten Site erlaubt ist. Falls das Feld leer bleibt, wird der Parameter locale in Storefront-Anfragen nicht verwendet.
Auth User
Ist die Beschränkung des Zugriffs in der Commerce Cloud aktiviert, muss in diesem Feld der User storefront angegeben werden.
Auth Password
In diesem Feld erfolgt die Angabe des zum storefront Users gehörenden Passworts.
Product Page Template Uid
Über den Produkte-Report können komfortabel Produkt-Detailseiten erstellt werden. Um dies zu ermöglichen, ist über dieses Konfigurationsfeld der Referenzname einer Seitenvorlage anzugeben, auf der die Produkt-Detailseiten basieren sollen.

In der gewählten Seitenvorlage ist zwingend das Feld dw_item_id erforderlich, um die ID des referenzierten Objektes zu speichern. Das Feld darf versteckt sein.

<CMS_INPUT_TEXT name="dw_item_id" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label=""/>
  </LANGINFOS>
</CMS_INPUT_TEXT>
Default Folder (Product Pages)
Für eine neue Produkt-Detailseite muss bekannt sein, wo diese in der Struktur einzubinden ist. Dafür kann an dieser Stelle optional der Referenzname eines Struktur-Ordners angegeben werden. In ihm werden anschließend alle neuen Produkt-Detailseiten erstellt. Bleibt das Feld leer, muss die Auswahl einer Menüebene durch den Redakteur erfolgen.
Editable Folder (Product Pages)
Mit dieser Checkbox lässt sich festlegen, ob die im Feld Default Folder (Product Pages) getroffene Auswahl durch einen Redakteur geändert werden kann. Initial ist die Funktion aktiviert. Ist sie deaktiviert, wird die entsprechende Eingabekomponente im Dialog zur Erstellung einer Detailseite versteckt. Der Redakteur besitzt in diesem Fall keine Möglichkeit, den Menüpunkt einer neu erstellten Detailseite zu wählen bzw. ändern.

Wird die Checkbox deaktiviert, muss zwingend der Referenzname eines Struktur-Ordners im Feld Default Folder (Product Pages) angegeben sein. Andernfalls ist die Erstellung neuer Detailseiten aufgrund der fehlenden Zuordnung zu einer Menüebene nicht möglich und es treten Fehler auf.

Category Page Template Uid

Über dieses Konfigurationsfeld kann das Mapping von Seitenvorlagen, für das Anlegen von Kategorie-Detailseiten über den Kategorie-Report, konfiguriert werden. Dabei gelten folgende Regeln:

  • Das Feld enthält genau eine Id einer FirstSpirit Seitenvorlage oder ein oder mehrere Mappings
  • Mappings werden durch eine kommaseparierte Liste angegeben <mapping>,<mapping>
  • Jedes Mapping ist folgendermaßen aufgebaut: <isml_template>:<fs_template>
  • Um für alle ISML-Templates, die kein explizites Mapping besitzen, eine Seitenvorlage zu konfigurieren, ist folgende Form zu verwenden: default:<fs_template>

Wir empfehlen, separate Vorlagen für Produkt- und Kategorie-Detailseiten zu verwenden.

Default Folder (Category Pages)
Äquivalent zu den Produkt-Detailseiten muss auch für jede neue Kategorie-Detailseite bekannt sein, wo diese in der Struktur einzubinden ist. Der Referenzname eines entsprechenden Struktur-Ordners kann an dieser Stelle optional angegeben werden. In ihm werden anschließend alle neuen Kategorie-Detailseiten erstellt. Bleibt das Feld leer, muss die Auswahl einer Menüebene durch den Redakteur erfolgen.
Editable Folder (Category Pages)
Äquivalent zur Checkbox Editable Folder (Product Pages) kann an dieser Stelle festgelegt werden, ob Redakteure die im Feld Default Folder (Category Pages) getroffene Auswahl ändern können. Initial ist die Funktion aktiviert. Ist sie deaktiviert, wird die Auswahlmöglichkeit im Dialog zur Erstellung einer Detailseite versteckt. Der Redakteur besitzt in diesem Fall keine Möglichkeit, den Menüpunkt für eine neue Detailseite zu wählen bzw. zu ändern.

Wird die Checkbox deaktiviert, muss zwingend der Referenzname eines Struktur-Ordners im Feld Default Folder (Category Pages) angegeben sein. Andernfalls ist die Erstellung neuer Detailseiten aufgrund der fehlenden Zuordnung zu einer Menüebene nicht möglich und es treten Fehler auf.

Template Instantiation Script Uid
Über dieses Konfigurationsfeld kann optional ein Skript gewählt werden, das vor und nach der Anlage von Detailseiten ausgeführt wird.

Es ist zu beachten, dass nur der Code aus dem html-Kanal des Skripts ausgeführt wird.

View Type Priority
Die Bilder der aus der Commerce Cloud stammenden Produkte werden stets in verschiedenen Größen bereitgestellt. Es kann jedoch nicht vorausgesetzt werden, dass für jede Größe ein Bild hinterlegt wurde. Aus diesem Grund kann an dieser Stelle kommasepariert die View Type Priority der zu berücksichtigenden Bildgrößen definiert werden.

Im auf der Abbildung Konfigurationsdialog der Projekt-Komponente dargestellten Fall wird für jedes Produkt das zugehörige große (large) Bild ermittelt und bei dessen Existenz verwendet. Liegt jedoch kein großes Bild vor, wird anschließend das mittelgroße (medium) bzw. gegebenenfalls das kleine (small) Bild abgerufen.

Da das Feld keine Pflichteingabe erwartet, kann es vorkommen, dass keine Priorität definiert wird und das Feld leer bleibt. In diesem Fall werden Suchergebnisse für eine Produktabfrage ohne ein Bild dargestellt.

Image Service Base URL
Die Commerce Cloud stellt einen sogenannten Image Service bereit. Dieser stellt zusätzliche Bilder für die verwendeten Produktbilder bereit. Ist seine Verwendung gewünscht, ist an dieser Stelle lediglich die zugehörige Base URL anzugeben.

Die Angabe der Image Service Base URL ist optional. Wird das Feld jedoch mit einer URL gefüllt, so muss diese Eingabe fehlerfrei sein. Andernfalls wird der jeweilige Report für die Produktsuche in beiden FirstSpirit-Clients ausgeblendet. Dies gilt auch dann, wenn die Client ID und die Base URL korrekt sind (siehe oben).

Kategorie-Report
Abbildung 6. Kategorie-Report


Test Configuration
Über den Button Test Configuration lassen sich die eingetragenen Eingaben überprüfen. Dabei werden die Client ID, die Base URL und - wenn vorhanden - die Image Service Base URL berücksichtigt.
Import Templates
Zuletzt können über den Button Import Templates diverse Vorlagen in das Projekt übertragen werden, die für die Verbindung von FirstSpirit und der Commerce Cloud zwingend erforderlich sind. Nach dem Import der Vorlagen, wird der Button ausgeblendet.

Da einige Vorlagen JSTL-Code beinhalten, muss vor dem Import der Präsentationskanal des Vorlagensatzes html auf JSP gesetzt werden. Andernfalls sind die Ausgabekanäle der importierten Vorlagen leer.

Des Weiteren muss die verwendete Konvertierungsregel die folgende Zeile enthalten: "0x24="$" Ist sie noch nicht vorhanden, kann sie über ServerManagerServer-EigenschaftenKonvertierungs-Regeln hinzugefügt werden.

html-Vorlagensatz
Abbildung 7. html-Vorlagensatz


3.1.5. Hinzufügen der Web-Komponenten

Für die Vorschau und den ContentCreator müssen zwei Web-Komponenten hinzugefügt werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenWeb-Komponenten.

Web-Komponenten in den Projekt-Eigenschaften
Abbildung 8. Web-Komponenten in den Projekt-Eigenschaften


Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, die jeweils eine Liste der bereits vorhandenen Web-Komponenten enthalten. Selektieren Sie nach dem Klicken auf Hinzufügen für die initial ausgewählte Registerkarte Vorschau die ContentConnect Web Resources und FS_JSTL_WebApp und bestätigen Sie die Auswahl mit OK.

Wiederholen Sie diesen Vorgang für den ContentCreator. Die Liste im Hauptpanel wird anschließend für beide Registerkarten um die jeweiligen Web-Komponenten ergänzt (vgl. Abbildung Web-Komponenten in den Projekt-Eigenschaften).

Die Web-Komponenten müssen auf einem aktiven Webserver installiert und danach aktiviert werden. Dieser kann über die Auswahlbox gewählt werden.

Detaillierte Informationen zum Hinzufügen von Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren.

3.1.6. Angabe der Einstellungsseite

Für die Funktionalitäten des ContentConnect-Moduls sind einige projektspezifische Informationen erforderlich. Die Informationen werden in den Projekteinstellungen angegeben.

Die Vorlage ist in den Projekt-Eigenschaften auszuwählen und muss dafür im Projekt existieren. Legen Sie sie zunächst an, wenn dies nicht zutreffen sollte. Andernfalls öffnen Sie den ServerManager und wechseln Sie auf den Bereich Projekt-EigenschaftenOptionen. Selektieren Sie anschließend die Einstellungs-Seite über den entsprechenden Auswahlbutton (vgl. Abbildung Optionen in den Projekt-Eigenschaften). Ein Klick auf den Button OK speichert die vorgenommenen Änderungen.

Optionen in den Projekt-Eigenschaften
Abbildung 9. Optionen in den Projekt-Eigenschaften


3.2. Commerce Cloud

In diesem Kapitel wird die Installation und Konfiguration der Commerce Cloud-seitigen Komponenten erläutert.

3.2.1. Einrichtung der Cartridge

In der Auslieferung ist die Cartridge int_firstspirit_cms enthalten, die zunächst in die Commerce Cloud übertragen werden muss. Verschiedene Methoden hierzu beschreibt die Commerce Cloud-Dokumentation unter Developing your storefront → Development components → Cartridges.

Anschließend muss die Cartridge allen Sites, die FirstSpirit-Inhalte empfangen sollen, sowie der Business-Manger-Site hinzugefügt werden. Entsprechende Instruktionen finden sich in der Commerce Cloud-Dokumentation unter Getting started → Getting started for developers → Registering your cartridge.

3.2.2. Einrichtung der Job Schedules

Um die von FirstSpirit generierten Inhalte und Slot-Konfigurationen in die Commerce Cloud zu importieren, ist für jede Site ein Job Schedule in der Commerce Cloud anzulegen. Die Cartridge definiert dazu zwei Job Steps:

  1. custom.FirstSpirit.ImportLibrary importiert die von FirstSpirit generierten Inhalte in die Commerce Cloud
  2. custom.FirstSpirit.ImportSlotConfigurations import die von FirstSpirit generierten Slot-Konfigurationen in die Commerce Cloud

Beide besitzen die Pflichtparameter Import File und Import Mode:

Import File
Pfad zur von FirstSpirit generieten XML-Datei, relativ zum IMPEX-Verzeichnis.
Import Mode
Legt fest, wie die importierten Objekte interpretiert werden.

Die Commerce Cloud-Dokumentation enthält eine Beschreibung der verschiedenen Import Modes: Administering your organization → Import and export → Import modes.

Der Job Schedule sollte einen Workflow mit zwei parallelen Flows enthalten. Jeder Flow kann dann einen der beiden oberen Job Steps aufrufen.

Neben der Cartridge enthält die Auslieferung im Verzeichnis metadata außerdem eine Export-Datei eines Job Schedules, der als Referenz genutzt werden kann und die Anlage der verschiedenen Job Schedules vereinfacht.

Da für jede Site ein Job anzulegen ist, muss das Attribut job-id des Tags job angepasst werden, um die Eindeutigkeit sicherzustellen. Es bietet sich an, die Id der jeweligen Site in die Job Id aufzunehmen.

Nach dem Import sind weitere Anpassung am Job Schedule notwendig. Der Scope beider Job Flows muss auf die richtige Site gesetzt werden. Ebenso ist der Import File-Parameter in beiden Job Steps anzupassen, sodass er den korrekten Pfad enthält.

Der Scope der Flows sowie der Parameter Import File können wie die Job Id auch vorab direkt in der Export-Datei angepasst werden.

4. Anpassungen im Projekt

Nach der Installation und Konfiguration der verschiedenen Komponenten sowie dem Import der Vorlagen müssen innerhalb des Projekts diverse Anpassungen vorgenommen werden. Die dafür notwendigen Schritte werden in den nachfolgenden Unterkapiteln erläutert.

4.1. Projekteinstellungen

Für die Verbindung zwischen FirstSpirit und der Commerce Cloud sind einige projektspezifische Informationen unentbehrlich (vgl. Abbildung Projekteinstellungen). Sie werden über das Formular der Projekteinstellungen erfasst und sind innerhalb des verwendeten Projekts anzugeben.

Projekteinstellungen
Abbildung 10. Projekteinstellungen


URL Protocol
Es ist zu entscheiden, ob FirstSpirit und die Commerce Cloud per http oder https miteinander kommunizieren sollen.
Instance
In diesem Feld ist die Commerce Cloud Instanz anzugeben.
Site ID
Die ID der verwendeten Commerce Cloud Site ist ebenfalls erforderlich.
Content Asset ID Prefix
Besteht der Wunsch ein Präfix für die eindeutige Identifizierung der Content Assets zu verwenden, kann es an dieser Stelle definiert werden. Alternativ kann das Präfix auch hardcoded innerhalb der Vorlagen verwendet werden.
Preview Protection (BasicAuth)
Innerhalb der Commerce Cloud lässt sich der Zugriff auf den Storefront schützen, indem der Site Status Online (protected) aktiviert wird. Besteht diese Einschränkung, muss in FirstSpirit der User storefront angegeben werden. Durch die Aktivierung der Checkbox werden die Felder User und Password eingeblendet.
User
Ist die Beschränkung des Zugriffs in der Commerce Cloud aktiviert, muss in diesem Feld der User storefront angegeben werden.
Password
In diesem Feld erfolgt die Angabe des zum storefront Users gehörenden Passworts.

Des Weiteren werden mit der Vorlage zwei XML-Kollektoren und ein Produkt-Manager initialisiert, die in den anderen Seiten- und Absatzvorlagen des Projekts genutzt werden. In diesen Seiten- und Absatzvorlagen wird festgelegt, welche Daten an die Commerce Cloud übergeben werden sollen. Während der Generierung werden die Daten auf Basis dieser Festlegungen gesammelt und die XML-Kollektoren gefüllt.

Bestehen für die XML-Kollektoren projektspezifische Anforderungen, so können sie über die Methoden der Klasse XmlCollectorFactoryExecutable angepasst werden. Die dafür notwendigen Informationen sind im Javadoc der Klasse enthalten.

Informationen zum Aufruf des Produkt-Managers sind im Javadoc der Klasse ManagerFactoryExecutable enthalten.

4.2. XML-Vorlage

Die Commerce Cloud erwartet alle an ihr übermittelten Daten in Form von XML-Dateien. Aus diesem Grund werden die im ersten Schritt der Generierung in die XML-Kollektoren geschriebenen Informationen im zweiten Schritt ausgelesen und in jeweils eine XML-Datei geschrieben.

Dafür muss der Generierungszeitpunkt der Dateien bestimmbar sein und sichergestellt werden, dass die Befüllung der XML-Kollektoren bereits abgeschlossen wurde. Diese Aufgabe übernimmt die XML-Vorlage. Sie besitzt eine Abfrage, mit der während der Generierung die Strukturvariable dwre_xmlGeneration ausgewertet wird.

Abfrage der Strukturvariablen dwre_xmlGeneration. 

$CMS_IF(!#global.preview)$
   $CMS_IF(!dwre_xmlGeneration.equals("true"))$
      $CMS_SET(#global.stopGenerate,true)$
   $CMS_END_IF$

   $CMS_VALUE(xmlCollector.getXml(true))$
$CMS_END_IF$

Die Variable wird erst im zweiten Schritt der Generierung über den Auftrag auf true gesetzt und besitzt ansonsten den Wert false. Damit werden auch die benötigten XML-Dateien erst zu diesem Zeitpunkt erzeugt. Ohne die Abfrage würden die XML-Kollektoren bereits im ersten Schritt ausgelesen. Dies hätte jedoch inkonsistente Datenstände zur Folge.

Mit der Vorlage lassen sich zwei XML-Dateien erzeugen. Dies erfolgt in beiden Fällen über einen Kollektor, für den jeweils eine auf der XML-Vorlage basierende Seitenreferenz benötigt wird. Im Formular der zugehörigen Seite muss der entsprechende XML-Kollektor ausgewählt werden.

Im Eigenschaften-Tab der Vorlage muss als Dateiendung xml definiert sein.

Die Generierung der folder-Tags erfordert eine projektspezifische Erweiterung der XML-Vorlage in Form einer Navigationsfunktion, die die notwendigen XML-Elemente erzeugt. Die Ausgabe dieser Funktion muss folglich ebenfalls an einer passenden Stelle ergänzt werden, worauf Kommentare in der importieren Vorlage nochmals hinweisen.

Das mitgelieferte Demoprojekt enthält eine beispielhafte Implementierung einer solchen Navigationsfunktion.

4.3. Formatvorlagen

Neben einigen technischen Formatvorlagen wird auch die Vorlage Preview Generation importiert. Über sie wird mithilfe von JSTL eine Abfrage an die Commerce Cloud versandt und das HTML-Gerüst der Seite angefordert. Dieses Gerüst wird durch die Ersetzung der bestehenden Platzhalter mit FirstSpirit-Inhalten angereichert. Auf diesem Weg kann den Redakteuren die Seite in der Vorschau des SiteArchitects bzw. im ContentCreator dargestellt werden.

Des Weiteren dient die Vorlage der Personalisierung. Sie ermöglicht die Anpassung der Darstellung bei der Selektion spezieller Zielgruppen. Ist auch die Filterung auf bestimmte Zeiträume gewünscht, muss der Code entsprechend erweitert werden.

Die Vorlage übernimmt somit mehrere Aufgaben und besitzt daher eine grundlegende Bedeutung innerhalb des Projekts.

4.4. Seitenvorlage

Die Commerce Cloud besitzt verschiedene Seitentypen, die neben einer URL zum Teil eine ID besitzen. Für die Darstelllung in der Vorschau bzw. im ContentCreator muss FirstSpirit anhand dieser Parameter die passende URL erzeugen, um die zugehörige Seite in der Commerce Cloud abfragen zu können. Dafür wurde die Formatvorlage Create Preview URL bereitgestellt.

Die Vorlage erwartet sowohl den Typ als auch - wenn sie existiert - die ID der zugehörigen Commerce Cloud-Seite. Aus diesem Grund muss jede verwendete Seitenvorlage die folgenden beiden Eingabekomponenten bereitstellen:

Radiobutton und Textfeld. 

<CMS_INPUT_RADIOBUTTON name="pt_dwre_previewType" gridWidth="3" hFill="yes">
   <ENTRIES>
      <ENTRY value="home">
         <LANGINFOS>
            <LANGINFO lang="*" label="Home"/>
         </LANGINFOS>
      </ENTRY>
      <ENTRY value="page">
         <LANGINFOS>
            <LANGINFO lang="*" label="Page"/>
         </LANGINFOS>
      </ENTRY>
      <ENTRY value="folder">
         <LANGINFOS>
            <LANGINFO lang="*" label="Folder"/>
         </LANGINFOS>
      </ENTRY>
      <ENTRY value="search">
         <LANGINFOS>
            <LANGINFO lang="*" label="Search"/>
         </LANGINFOS>
      </ENTRY>
   </ENTRIES>
   <LANGINFOS>
      <LANGINFO lang="*" label="Preview Page Type"/>
   </LANGINFOS>
</CMS_INPUT_RADIOBUTTON>

<CMS_INPUT_TEXT name="pt_dwre_previewPageId" hFill="yes" hidden="no">
   <LANGINFOS>
      <LANGINFO lang="*" label="SFCC Preview Page Identifier (Page-Show:CID / Page-Search:CGID)"/>
   </LANGINFOS>
</CMS_INPUT_TEXT>

Die Weiterverarbeitung der mit diesen Komponenten erfassten Daten erfolgt über die initial importierten Formatvorlagen Default Page Header und Preview Generation. Sie müssen über einen CMS_RENDER-Aufruf in den verwendeten Seitenvorlagen referenziert werden. Dabei ist zu beachten, dass die beiden Formatvorlagen nur die FirstSpirit-Vorschau beeinflussen. Es sollte daher eine entsprechende Unterscheidung vorgenommen werden:

Referenzierung der Formatvorlagen. 

$CMS_IF(!#global.preview)$
   [...] // Codepointer 1
$CMS_ELSE$
   $CMS_RENDER(template:"default_page_header")$
   [...] // Codepointer 2
   $CMS_RENDER(template:"preview_generation")$
$CMS_END_IF$

Codepointer 1
Im sich nicht auf die Vorschau beziehenden Teil der Abfrage ist festzulegen, mit welchen Daten die in den Projekteinstellungen initialisierten XML-Kollektoren gefüllt werden sollen. Dies erfolgt über CMS_SET-Aufrufe und die add-Methoden der Kollektoren. Das mit dem Modul ausgelieferte Projekt enthält beispielsweise innerhalb der Seitenvorlagen den nachstehenden Aufruf:

$CMS_SET(void,ps_xmlCollector.addContentAttribute({
   "name":"display-name",
   "value":#global.node.getDisplayName(#global.language).toString(),
   "attributes":{"xml:lang":set_xml_lang} }))$`

Der Aufruf erzeugt das Tag display-name, das in der generierten XML-Datei über folgenden Aufbau verfügt:

<display-name xml:lang="en"><![CDATA[About Us]]></display-name>

Es besitzt als Wert den Anzeigenamen der aktuellen Seite. Außerdem wird ihm die Sprache als Parameter mitgegeben.

Codepointer 2
Zwischen den beiden CMS_RENDER-Aufrufen findet die Ersetzung der aus der Commerce Cloud stammenden Platzhalter statt. Dafür ist zu definieren, welcher Platzhalter an dieser Stelle durch welche FirstSpirit-Inhalte auszutauschen ist. Dies erfolgt ebenfalls über CMS_SET-Aufrufe und die Methoden stringToReplace bzw. stringToInsert. Das mitgelieferte Projekt enthält dafür beispielsweise innerhalb der Seitenvorlage Homepage den nachfolgenden Aufruf. Durch ihn wird in diesem Fall in der Vorschau und im ContentCreator statt des Platzhalters der in FirstSpirit gepflegte Inhaltsbereich fs_home_cycle angezeigt.

$CMS_SET(void, stringToReplace.add(
   "<!-- CMS-CONTENT-CYCLE-START -->(?s:.)*<!-- CMS-CONTENT-CYCLE-END -->"))$
$CMS_SET(stringToInsert[stringToReplace.size-1])$
   <div$CMS_VALUE(editorId(element:#global.page.body("fs_home_cycle")))$>
      $CMS_VALUE(#global.page.body("fs_home_cycle"))$
   </div>
$CMS_END_SET$

Beide Punkte müssen projektspezifisch erfolgen und können im mitgelieferten Beispielprojekt nachvollzogen werden.

Zur Verwendung der Content Integration API sind weitere Punkte zu beachten, die in Kapitel Seitenvorlage für redaktionelle Inhalte beschrieben sind.

4.5. Strukturvariable

Die Commerce Cloud erwartet alle an ihr übermittelten Daten in Form von XML-Dateien. Sie dürfen erst nach der Befüllung der XML-Kollektoren erzeugt werden, da ansonsten von Datenverlusten auszugehen ist. Die Steuerung des Erstellungszeitpunkts der Dateien erfolgt über die Strukturvariable dwre_xmlGeneration, die manuell anzulegen ist.

Öffnen Sie dafür die Strukturverwaltung ihres Projekts und selektieren Sie die Registerkarte Root-KnotenVariablen, bevor Sie den Bearbeitungsmodus aktivieren. Vergeben Sie dann in dem sich über den Button Neue Variable anlegen öffnenden Dialog den Namen dwre_xmlGeneration. Bestätigen Sie die Angabe mit OK und vergeben Sie im sich darauf öffnenden Dialog den Wert false. Schließen Sie den Dialog, indem Sie den Wert Für alle Sprachen übernehmen.

Wert der Strukturvariable
Abbildung 11. Wert der Strukturvariable


Im zweiten Schritt der Generierung erhält die Variable über den Auftrag den Wert true. Eine Abfrage innerhalb der XML-Vorlage regelt auf diesem Weg den Erstellungszeitpunkt der an die Commerce Cloud zu übermittelnden XML-Dateien.

5. Commerce Cloud-Inhalte in FirstSpirit

Sowohl im SiteArchitect als auch im ContentCreator wird durch das ContentConnect-Modul ein Report bereitgestellt. Dieser Report dient der Darstellung der Produktinformationen aus der Commerce Cloud. Wenn die Projektkomponente entsprechend konfiguriert wurde, kann die Suche auf eine Kategorie und ihre Unterkategorien beschränkt werden. Die Abbildung Produkte-Report zeigt den Report links ohne und rechts mit dem Kategorie-Filter.

Produkte-Report
Abbildung 12. Produkte-Report


Um eine Produktsuche durchzuführen, muss mindestens einer der beiden Parameter (Kategorie, Suchbegriff) angegeben werden. Falls eine Kategorie ausgewählt wird, zeigt der Report alle Produkte dieser Kategorie an, die zum eingegebenen Suchbegriff passen. Sollte dieser Begriff leer sein, werden alle Produkte der ausgewählten Kategorie abgerufen. Wird hingegen keine spezielle Kategorie selektiert, werden alle Kategorien nach dem eingegebenen Begriff durchsucht. Wenn der Kategorie-Filter inaktiv ist, wird keine Kategorie zur Filterung genutzt und der Report verhält sich entsprechend.

In der Commerce Cloud existieren zu einem Master-Produkt unterschiedliche Produktvarianten, die bei einer Standardsuche nicht im Report angezeigt werden. Über die Suche nach ihrer ID können sie jedoch ebenfalls gefunden und verwendet werden

Neben dem Produkte-Report bietet das ContentConnect-Modul auch einen optionalen Kategorie-Report. Die Daten dieses Reports können analog zu den Daten des Produkte-Reports verwendet werden.

5.1. Redaktionelle Inhalte

Die Daten des Reports können für die Erstellung und Pflege redaktioneller Inhalte weiterverwendet werden. Dafür müssen den Redakteuren entsprechende Mittel bereitgestellt werden. Dies ist grundsätzlich auf verschiedenste Weisen möglich. Die jeweils optimale Umsetzung muss daher immer individuell auf Basis der bestehenden projektspezifischen Anforderung ermittelt werden.

Innerhalb des mitgelieferten Beispielprojekts können sowohl mehrere Commerce Cloud-Produkte über eine FS_LIST als auch nur ein einziges Produkt über eine Verweisvorlage referenziert werden. Bei der Verwendung der FS_LIST wird ihr für jedes gewählte Produkt ein neuer Eintrag hinzugefügt und die Produktinformationen in diesem gespeichert. Im Gegensatz dazu werden die Informationen bei der Verweisvorlage direkt im Formular hinterlegt. Beide Wege divergieren bei der Implementierung lediglich in einem Punkt, der im nachfolgenden Kapitel Formular erläutert wird.

Abhängig vom Anwendungsfall können bei der Ausgabe der referenzierten Produkte unterschiedliche Informationen erforderlich sein. Bei der Darstellung "ähnlicher Produkte" bietet sich beispielsweise die Verwendung allgemeiner Daten an, während für sogenannte "Hot Spots" spezifische Variantionsattribute benötigt werden. Die Ermittlung und Ausgabe der Informationen für diese beiden Fälle wird in den nachfolgenden Unterkapiteln Ausgabe allgemeiner Produktinformationen und Verlinkung von Produktvarianten beschrieben.

5.1.1. Formular

Die beiden im vorgehenden Kapitel erwähnten Wege zur Referenzierung von Commerce Cloud-Produkten divergieren nur in einem Punkt. Aus diesem Grund wird in diesem Kapitel vorrangig die Umsetzung der FS_LIST skizziert und auf den Unterschied zur Verweisvorlage lediglich an entsprechender Stelle hingewiesen.

Die FS_LIST ist im Beispielprojekt in der Absatzvorlage Featured Products definiert, deren Formular sich außerdem aus den beiden Buttons clickHandler und dropHandler zusammensetzt. Beide Buttons verwenden die Klasse Demandware_ProductDropHandler, die ein Bestandteil des ContentConnect-Moduls ist und die Übertragung eines Commerce Cloud-Produkts regelt.

<FS_LIST name="st_productList" hFill="yes" height="400">
   <DATASOURCE type="inline" useLanguages="yes">
      <LABELS>
         <LABEL lang="*">#item.name</LABEL>
      </LABELS>
      [...]
      <TEMPLATES source="linktemplates">
         <TEMPLATE uid="list_product_link"/>
      </TEMPLATES>
   </DATASOURCE>
</FS_LIST>

<FS_BUTTON
    name="dropHandler"
    icon="media:drop_zone_product"
    noBreak="yes"
    onDrop="class:DemandwareConnect_ProductDropHandler"
    style="link">

   <DROPTYPES>
        <MIME type="application/x-java-serialized-object"
            classname="com.espirit.moddev.demandware.products.Product"/>
   </DROPTYPES>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

<FS_BUTTON name="clickHandler" onClick="class:DemandwareConnect_ProductDropHandler">
   <LANGINFOS>
      <LANGINFO lang="*" label="Add product from selection"/>
   </LANGINFOS>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

Beide Buttons werden auch in der Verweisvorlage Product Hot Spot verwendet. Dort müssen die Parameter der Buttons jedoch anders definiert werden:

<PARAMS>
   <PARAM name="id">#field.id</PARAM>
   <PARAM name="name">#field.name</PARAM>
   <PARAM name="variationAttributes">#field.variationAttributes</PARAM>
</PARAMS>

Dieser Unterschied basiert auf der Tatsache, dass die Felder id und name im Formular der Verweisvorlage parallel zu den beiden Buttons platziert sind. Sie werden daher über den vorangestellten Ausdruck #field direkt angesprochen. In der Absatzvorlage Featured Products sind die Buttons hingegen parallel zur FS_LIST angeordnet und die Felder id und name in der von ihr referenzierten Verweisvorlage list_product_link enthalten.

Die beiden Buttons im Formular der Verweisvorlage besitzen außerdem den Parameter variationAttributes, der ein verstecktes Textfeld anspricht. Dieses wird für die Persistierung der einem Produkt zugehörigen spezifischen Variationsattribute verwendet. Da die Absatzvorlage Featured Products lediglich der Ausgabe allgemeiner Produktinformationen dient, benötigen die Buttons in ihrem Formular diesen Parameter nicht.

Die Buttons ermöglichen den Redakteuren eine schnelle und unkomplizierte Referenzierung der Commerce Cloud-Produkte in FirstSpirit, ohne dass dabei der Client verlassen werden muss. Andernfalls müssten die Produktinformationen in der Commerce Cloud ermittelt und dann manuell übertragen werden. Pro FirstSpirit-Client wird immer nur einer der beiden Buttons angezeigt.

dropHandler
Dieser Button wird im ContentCreator verwendet und dort als Fläche dargestellt (vgl. Abbildung DropHandler). Die Referenzierung der Commerce Cloud-Produkte findet per Drag & Drop aus dem Report heraus auf diese Fläche statt.
DropHandler
Abbildung 13. DropHandler


clickHandler
Dieser Button ermöglicht die Referenzierung der Commerce Cloud-Produkte im SiteArchitect. In ihm ist die Übernahme per Drag & Drop - im Gegensatz zum ContentCreator - nicht möglich. Daher wird beim Hovern über ein im Report dargestelltes Produkt der Button Copy to product clipboard eingeblendet. Ein Klick auf ihn kopiert die gewünschten Informationen in eine vom Modul bereitgestellte Zwischenablage. Die Übernahme dieser Informationen erfolgt anschließend über den im Formular enthaltenen Button Add product from selection (vgl. Abbildung ClickHandler).
ClickHandler
Abbildung 14. ClickHandler


Wie bereits zuvor erwähnt, sind die Buttons spezifisch für jeweils einen der beiden FirstSpirit-Clients. Sie müssen daher im entsprechend anderen Client ausgeblendet werden. Diese Anforderung wird über die Regeln gesteuert, die sowohl in der genannten Absatz- als auch in der Verweisvorlage definiert sind.

Die erste Abfrage aktiviert den Button clickHandler, wenn ein im Report dargestelltes Commerce Cloud-Produkt in die Zwischenablage kopiert wurde.
Die letzten beiden Abfragen prüfen, ob der aktuelle Redakteur sich im ContentCreator befindet. Befindet er sich im SiteArchitect, wird der Button clickHandler eingeblendet. Andernfalls ist der Button dropHandler sichtbar.

<RULES>
   <ON_EVENT>
      <SCHEDULE service="DemandwareConnect_ClipboardFilled" id="product_link_clipboard_check">
         <!-- Some FS versions complain about an invalid rule definition without a parameter -->
         <PARAM name="dummy">
            <TEXT>dummy</TEXT>
         </PARAM>
      </SCHEDULE>
      <DO>
         <PROPERTY source="clickHandler" name="EDITABLE" />
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <NOT>
            <PROPERTY source="#global" name="WEB"/>
         </NOT>
      </WITH>
      <DO>
         <PROPERTY source="clickHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <PROPERTY source="#global" name="WEB"/>
      </WITH>
      <DO>
         <PROPERTY source="dropHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>
</RULES>

Existiert im Formular der verwendeten Vorlage das Textfeld variationAttributes, öffnet sich bei der Referenzierung eines Master-Produkts über einen der beiden Buttons ein zusätzlicher Dialog. Dieser stellt alle dem ausgewählten Produkt zugehörigen Variationsattribute dar, über die sich die Produktauswahl spezifizieren lässt.(vgl. Abbildung Spezifikation eines Produkts).

Ergibt sich durch die Spezifikation die Definition einer bestimmten Produktvariante, werden in den Feldern id und name der Verweisvorlage bzw. der FS_LIST die Informationen dieser Variante gespeichert. Andernfalls werden die Id und der Name des Master-Produkts übernommen und die im Dialog definierten Variationsattribute in Form eines JSONs im versteckten Feld variationAttributes persistiert.

Spezifikation eines Produkts
Abbildung 15. Spezifikation eines Produkts


5.1.2. Ausgabe allgemeiner Produktinformationen

Für die Darstellung referenzierter Produkte in der Vorschau können mithilfe des Produkt-Managers weitere Produktinformationen abgefragt werden. Der Produkt-Manager wird in den Projekteinstellungen initialisiert, deren Vorlage während der Konfiguration der Projektkomponente in das Projekt importiert wurde. Je nach Anwendungsfall können mit ihm sowohl spezifische Variationsattribute als auch allgemeine Produktinformationen ermittelt werden.

Dieses Kapitel skizziert die Idee einer Liste "ähnlicher Produkte". In diesem Fall werden lediglich allgemeine Informationen, wie beispielsweise der Name und der Preis eines Produkts, benötigt. Spezifische Attribute sind hingegen an dieser Stelle nicht von Bedeutung.

Das nachfolgende Beispiel basiert auf der Annahme, dass für die Referenzierung der Produkte die zuvor beschriebene FS_LIST verwendet wurde. Es kann anhand der Absatzvorlage Featured Products nachvollzogen werden.

Jedes in der FS_LIST referenzierte Produkt wird beim Durchlaufen der FOR-Schleife zunächst über den Produkt-Manager geladen. Befindet sich der Redakteur in der Vorschau, werden anschließend durch die Verwendung einfacher Getter-Methoden das Produktbild, der Name und der Preis ermittelt und dargestellt.

$CMS_FOR(for_product,st_productList)$
   $CMS_IF(!for_product.id.isEmpty)$
      $CMS_SET(set_product,ps_productManager.loadProduct(for_product.id))$
      [...]
      $CMS_IF(!#global.preview)$
         [...]
      $CMS_ELSE$
         $-- FirstSpirit Preview --$
         <li>
            <div class="product-tile">
               <div class="product-image">
                  <a class="thumb-link" href="#" title="">
                     <img src="$CMS_VALUE(set_product.getImageUrl(set_width,set_height))$">
                  </a>
               </div>
               <div class="product-name">
                  <a class="name-link" href="#">
                     $CMS_VALUE(set_product.getName())$
                  </a>
                  <div class="product-price">
                     <span class="price-sales">
                        $CMS_VALUE(set_product.getCurrency())$
                        $CMS_VALUE(set_product.getPrice().format("0.00"))$
                     </span>
                  </div>
               </div>
               [...]
            </div>
         </li>
      $CMS_END_IF$
   $CMS_END_IF$
$CMS_END_FOR$

5.1.3. Verlinkung von Produktvarianten

Im Gegensatz zur im vorhergehenden Kapitel beschriebenen Darstellung allgemeiner Daten können mithilfe des Produkt-Managers auch spezifische Produktinformationen abgefragt werden.

Dieses Kapitel beschreibt die Idee sogenannter "Hot Spots". Dabei handelt es sich um gezielte Verweise auf spezifische Produktvarianten. Für sie werden die der jeweiligen Variante zugehörigen Variationsattribute benötigt. Die allgemeinen Informationen sind hingegen an dieser Stelle nicht von Bedeutung.

Das nachfolgende Beispiel basiert auf der Annahme, dass für die Referenzierung eines Produkts die zuvor beschriebene Verweisvorlage Product Hot Spot verwendet wurde. Anhand der Vorlage lässt sich das Beispiel nachvollziehen.

Für ein über die Verweisvorlage referenziertes Produkt wird zunächst ein Link auf die Commerce Cloud-Pipeline LinkProduct generiert und diesem die Id des Produkts übergeben. Handelt es sich bereits um eine spezifische Variante, ist das Feld variationAttributes leer. Andernfalls lädt der Produktmanager nacheinander alle in dem Feld gespeicherten Variationsattribute, die bei der Referenzierung des Produkts definiert wurden. Für jedes dieser Attribute wird dessen Id (z.B. "Farbe") sowie der gewählten Wert (z.B. "gelb") ermittelt und aus ihnen eine per "&"-Zeichen separierte Liste erzeugt. Der initial erzeugte Link auf die Commerce Cloud-Pipeline LinkProduct wird abschließend um diese Liste ergänzt.

$CMS_IF(!#global.preview)$
   $CMS_SET(set_lt_link,"$link-product:pid="+id+"$&")$

   $CMS_IF(!variationAttributes.isEmpty)$
      $CMS_SET(set_attributes, ps_productManager.convertVariationValuesJSON2List(variationAttributes).map(x -> x.key + "=" + x.value).toString("&"))
      $CMS_SET(set_lt_link, set_lt_link + set_attributes)$
   $CMS_END_IF$
$CMS_END_IF$

<a href="$CMS_VALUE(set_lt_link)$"> ... </a>

5.2. Detailseiten

Über den entsprechenden Report können sowohl für Produkte als auch für Kategorien jeweils Detailseiten angelegt werden. Zur Verwendung dieses Features muss in der Projekt-Komponente definiert werden, auf welchen Vorlagen diese Detailseiten basieren und wo sie in der Struktur eingebunden werden sollen.

Ein Objekt im Report kann bezüglich seiner Detailseite einen von drei Zuständen besitzen:

  1. Es ist keine Detailseite vorhanden und sie kann daher angelegt werden.
  2. Es ist bereits eine Detailseite vorhanden, die aufgerufen werden kann.
  3. Es ist bereits eine Detailseite vorhanden, für die jedoch entweder die Seitenreferenz oder die Seite nicht mehr gefunden werden kann.

Die drei Fälle werden unterschiedlich visualisiert und in den nachfolgenden Unterkapiteln beschrieben.

Da die Objekte im Report nicht permanent aktualisiert werden, kann es zu Abweichungen in der Visualisierung kommen.

5.2.1. Anlegen einer Detailseite

Objekte, die noch keine Detailseite besitzen, werden im Report durch ein graues Icon markiert (vgl. Abbildung Anlegen einer Detailseite). Wurde in der Projekt-Komponente eine Seitenvorlage definiert, erscheint beim Überfahren eines solchen Objekts die Schaltfläche .

Anlegen einer Detailseite
Abbildung 16. Anlegen einer Detailseite


Per Klick auf diese Schaltfläche öffnet sich ein zweigeteilter Dialog, mit dem sich für das entsprechende Objekt eine Detailseite anlegen lässt.

Der obere Teil des Dialogs ist der Struktur-Auswahl-Bereich, der automatisch eingefügt wird und damit immer gleich ist. Er stellt dem Redakteur die Möglichkeit zur Verfügung, innerhalb der Struktur die Menüebene auszuwählen, in der die neue Detailseite erzeugt wird. Potentiell ist die entsprechende Eingabekomponente schon vorbelegt. Dann wurde im Konfigurationsdialog der Projekt-Komponente bereits ein Struktur-Ordner definiert. Es steht dem Redakteur jedoch frei, diese Auswahl anzupassen.

Unter Umständen ist der Struktur-Auswahl-Bereich im Dialog ausgeblendet. In diesem Fall ist in der Projekt-Komponente ebenfalls bereits ein Struktur-Ordner vordefiniert. Gleichzeitig wurde jedoch festgelegt, dass der Redakteur diese Vorbelegung nicht ändern können soll.

Im Gegensatz zum Struktur-Auswahl-Bereich ist der untere Formular-Bereich immer projektspezifisch. Er zeigt das Formular der in der Projekt-Komponente angegebenen Seitenvorlage. In ihm gelten außerdem die in der Vorlage definierten Regeln.

Die folgende Abbildung zeigt einen beispielhaften Dialog:

Dialog zum Anlegen einer Detailseite
Abbildung 17. Dialog zum Anlegen einer Detailseite


Ein Klick auf Anlegen erzeugt die Seitenreferenz der Detailseite in der zuvor gewählten Menüebene. Die zugehörige Seite wird in einem festem Ordner in der Inhalte-Verwaltung erstellt.

Ist innerhalb der Projekt-Komponente außerdem ein Skript angegeben, so wird dieses vor und nach der Erzeugung der Detailseite ausgeführt.

Es ist zu beachten, dass nur der Code aus dem html-Kanal des Skripts ausgeführt wird.

Diesem Skript werden die folgenden Parameter übergeben:

DatentypObjektnameBeschreibung

BaseContext

context

Der Kontext, in dem das Skript ausgeführt wird.

boolean

beforeInstantiation

true, falls die Ausführung vor der Seitenerstellung durchgeführt wird, ansonsten false.

KeyProvider

keyProvider

Das Objekt, für das eine Detailseite angelegt wird. Hierbei handelt es sich entweder um ein Product oder um eine Category.

Eine Erläuterung der Schnittstellen KeyProvider, Product und Category findet sich in der mitgelieferten Javadoc-Dokumentation.

Nach der vollständigen Erzeugung der Detailseite und dem Ausführen des Skriptes wird die neu erstellte Seite aufgerufen.

5.2.2. Aufruf einer vorhandenen Detailseite

Objekte, für die bereits eine Detailseite existiert, werden im Report durch einen grünes Icon markiert (vgl. Abbildung Produkt mit Detailseite). Sie erhalten beim Überfahren die Schaltfläche , mit der die zugehörige Detailseite aufgerufen werden kann.

Produkt mit Detailseite
Abbildung 18. Produkt mit Detailseite


5.2.3. Defekte Referenz auf eine Detailseite

Besitzt ein Objekt eine Detailseite, für die jedoch die Seitenreferenz oder die zugrunde liegende Seite nicht gefunden werden kann, so wird das Objekt im Report mit einem rotes Icon markiert (vgl. Abbildung Objekt mit Defekt). Solche Objekte erhalten beim Überfahren die Schaltfläche . Ein Klick auf diese Schaltfläche öffnet einen Dialog, der weitere Informationen bereit hält.

Objekt mit Defekt
Abbildung 19. Objekt mit Defekt


6. Deployment-Auftrag

Für die Übermittlung der in FirstSpirit erstellten Inhalte in den Commerce Cloud Storage wird ein Auftrag benötigt, der mindestens die nachfolgend erläuterten Aktionen enthält (vgl. Abbildung Aktionen des Generierungsauftrags). Zur Verwendung der Content Integration API ist darüber hinaus eine weitere Aktion erforderlich.

Öffnen Sie für den benötigten Auftrag den ServerManager und wählen Sie den Bereich Projekt-EigenschaftenAuftragsverwaltung. Fügen Sie dort einen neuen Standard-Auftrag hinzu oder bearbeiten Sie einen bereits bestehenden Auftrag.

Weitere Informationen zur Erstellung eines Auftrags finden Sie auch in der FirstSpirit Dokumentation für Administratoren.

Aktionen des Generierungsauftrags
Abbildung 20. Aktionen des Generierungsauftrags


6.1. Content Preparation - Vollgenerierung

Für das Deployment der für die Commerce Cloud relevanten Inhalte müssen diese zunächst aus dem Projekt ermittelt werden. Dafür muss eine Vollgenerierung durchgeführt werden, die alle referenzierten Medien in der richtigen Auflösung generiert. Außerdem erzeugt sie die in den Projekteinstellungen initialisierten XML-Kollektoren und füllt sie anhand der in den Vorlagen enthaltenen xmlCollector-Aufrufe.

Fügen Sie dem Auftrag daher zuerst eine Generierungsaktion hinzu und wählen Sie für diese einen beliebigen Namen. In den Eigenschaften sind außerdem die folgenden Optionen zu wählen (vgl. Abbildung Aktion Content Preparation):

  • Vollgenerierung durchführen
  • Generierungsverzeichnis vorher leeren
  • Medien im Generierungsverzeichnis erzeugen

Der Einsatz des WebDAV-Moduls ist nur in Verbindung mit dem Standard-Url-Creator möglich. Wählen Sie für die Pfaderzeugung daher zwingend den Eintrag Default URLs.

Des Weiteren ist ein beliebiges Präfix für absolute Pfade zu definieren. Dieses wird in der letzten Aktion WebDAV-Deployment benötigt.

Wechseln Sie anschließend auf die Registerkarte Erweitert und selektieren Sie die Vorlagensätze aller im Projekt vorhandenen Sprachen.

Aktion Content Preparation
Abbildung 21. Aktion Content Preparation


6.2. XML Import File - Teilgenerierungen

Alle an die Commerce Cloud übermittelten Daten werden von dieser in Form von XML-Dateien erwartet. Aus diesem Grund müssen die während der Vollgenerierung ermittelten Informationen aus den erzeugten XML-Kollektoren ausgelesen werden. Sie sollen stattdessen in eine jeweils zu erstellende XML-Datei geschrieben werden.

Fügen Sie dem Auftrag daher für jeden in den Projekteinstellungen initialisierten XML-Kollektor eine weitere Generierungsaktion hinzu und benennen Sie diese beliebig. Selektieren Sie anschließend in den Eigenschaften die Option Teilgenerierung durchführen für folgende Startpunkte.

Ein Klick auf den Button Hinzufügen öffnet einen separaten Dialog, der die Struktur- und die Medien-Verwaltung anzeigt. Wählen Sie für jede Aktion jeweils eine der auf der XML-Vorlage basierenden Seitenreferenzen und bestätigen Sie die Auswahl mit OK. Die Seitenreferenz wird daraufhin als Startknoten in den Eigenschaften der Generierungsaktion angezeigt (vgl. Abbildung Teilgenerierung).

Wechseln Sie anschließend auf die Registerkarte Erweitert und legen Sie über den Button Hinzufügen die Variable dwre_xmlGeneration an. Sie muss den Wert true erhalten.

Mit der Variablen und über die Auswahl des Startknotens kann sichergestellt werden, dass die selektierte Seitenreferenz erst zu diesem Zeitpunkt generiert wird. Somit liegen alle benötigten Informationen für die Erstellung der XML-Datei bereits vor und es können keine Lücken auftreten. Die Erzeugung der XML-Datei wird durch die im Projekt enthaltene XML-Vorlage gesteuert.

Teilgenerierung
Abbildung 22. Teilgenerierung


6.3. WebDAV-Deployment

Die mit den Teilgenerierungen erzeugten XML-Dateien müssen abschließend an die Commerce Cloud übermittelt werden. Die Publizierung erfolgt über ein Skript, das dem Auftrag zwingend als letzte Aktion hinzuzufügen ist und den folgenden Aufruf enthält:

Deployment-Skript. 

#!executable-class
com.espirit.ps.custom.deploy.WebDavDeployment

Öffnen Sie anschließend per Klick auf den Button Eigenschaften den gleichnamigen Dialog und legen Sie die folgenden Parameter an (vgl. Abbildung Eigenschaften):

Eigenschaften
Abbildung 23. Eigenschaften


url
Die URL gibt den Host und den Pfad auf dem WebDAV-Server an. Sie besitzt immer die folgende Struktur:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…​/<PREFIX>/<SITE ID>

Der Pfad entspricht dem Ort, an dem die jeweilige XML-Datei während des Imports erwartet wird. Er muss auf ein bereits existierendes Verzeichnis verweisen.

Des Weiteren muss das Präfix dem Präfix für absolute Pfade der Vollgenerierung entsprechen.

user
Für die Übertragung der Daten wird ein technischer User benötigt, der zur Nutzung der WebDAV-Schnittstelle berechtigt ist. Er muss Schreibrechte besitzen und ist an dieser Stelle mit seinem Namen anzugeben.
password
Für den zuvor angegebenen User wird zusätzlich die Angabe des Passworts benötigt.

Der technische Benutzer unterliegt den durch die Commerce Cloud definierten Passwort-Bestimmungen. Diese erfordern eine vierteljährliche Änderung des Passworts. Der Wert des Parameters muss in jedem dieser Fälle zwingend angepasst werden.

mediaurl
Der bei der Generierung erzeugte Medien-Ordner und sein Inhalt müssen in ein separates Verzeichnis übertragen werden, um der Commerce Cloud den Import zu ermöglichen. Dieses Verzeichnis ist über den Parameter mediaurl festzulegen. Die mediaurl besitzt immer die folgende Struktur:

http://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID>/default/<PREFIX>
srcprefixdir
Soll nur ein bestimmtes Verzeichnis an die Commerce Cloud übertragen werden, kann es über den optionalen Parameter srcprefixdir relativ zum Root-Knoten des Generierungsverzeichnisses angegeben werden. Wird der Parameter nicht definiert oder für ihn kein Wert gespeichert, wird das gesamte Generierungsverzeichnis übertragen.
purge
Dieser Parameter ist optional und kann nur den Wert true oder false besitzt. Der Wert true bewirkt, dass alle Dateien und Verzeichnisse unterhalb der angegebenen URL vor dem Start der Übertragung gelöscht werden. Besitzt der Parameter den Wert false oder garkeinen Wert, bleiben alle bestehenden Dateien und Verzeichnisse unterhalb der angegebenen URL bestehen. Neue Daten werden entweder hinzugefügt oder im Fall von bereits existierenden Daten überschrieben.

Das WebDav-Deployment darf nicht im Fehlerfall ausgeführt werden.

7. Personalisierung

Die Commerce Cloud bietet die Möglichkeit, Inhalte nur für spezielle Zielgruppen oder bestimmte Zeiträume anzeigen zu lassen. Soll eine solche Personalisierung durch die Redakteure in FirstSpirit definiert werden können, müssen einige Voraussetzungen geschaffen werden. Diese werden nachfolgend für die Eingrenzung der Inhalte auf Zielgruppen erläutert und anhand des mitgelieferten Beispielprojekts beschrieben.

7.1. Datenquelle

Die Filterung der redaktionellen Inhalte erfolgt auf der Basis auswählbarer Zielgruppen, die Commerce Cloud-seitig definiert werden. Die Commerce Cloud bietet jedoch keine Möglichkeit, diese Gruppen auszulesen und in FirstSpirit bereitzustellen. Aus diesem Grund muss innerhalb des FirstSpirit-Projekts eine Datenquelle erstellt werden, in der dieselben Zielgruppen manuell anzulegen sind. Jeder Datensatz muss dabei mindestens die aus der Commerce Cloud stammende ID sowie einen beliebig wählbaren Namen besitzen (vgl. Abbildung Zielgruppen in FirstSpirit).

Weitere Informationen zur Erstellung einer Datenquelle erhalten Sie in der FirstSpirit Online Dokumentation.

Zielgruppen in FirstSpirit
Abbildung 24. Zielgruppen in FirstSpirit


7.2. Eingabekomponente

Die Bereitstellung der Zielgruppen für die Redakteure erfolgt im Formular einer Seite oder eines Absatzes. Grundsätzlich bestehen diesbezüglich keine Einschränkungen und die Darstellung kann beliebig umgesetzt werden. Es bietet sich jedoch die Verwendung einer der folgenden Eingabekomponenten an:

  • CMS_INPUT_CHECKBOX
  • CMS_INPUT_COMBOBOX
  • CMS_INPUT_LIST
  • CMS_INPUT_RADIOBUTTON

Innerhalb des mitgelieferten Beispielsprojekts werden die Zielgruppen über eine Combobox zur Verfügung gestellt:

Combobox. 

<CMS_INPUT_COMBOBOX name="st_role">
   <CMS_INCLUDE_OPTIONS type="database">
      <LABELS>
         <LABEL lang="*">#item.name</LABEL>
      </LABELS>
      <TABLE>standard.roles</TABLE>
   </CMS_INCLUDE_OPTIONS>
   <LANGINFOS>
      <LANGINFO lang="*" label="Customer Group"/>
   </LANGINFOS>
</CMS_INPUT_COMBOBOX>

Diese ist in den verwendeten Absatzvorlagen enthalten und referenziert die Datensätze der erstellten Datenquelle.

Bereitstellung der Zielgruppen im Formular
Abbildung 25. Bereitstellung der Zielgruppen im Formular


Über die Auswahl einer Zielgruppe wird ihr der redaktionelle Inhalt zugeordnet. Mit dem Deployment wird diese Zuordung zur Commerce Cloud übertragen und dort auf die tatsächliche Zielgruppe gemapped. Damit bleibt die Personalisierung auch im Live-Stand erhalten und wird dort angewandt.

7.3. Multi Perspective Preview

Mit der Verwendung der Multi Perspective Preview wird den Redakteuren im ContentCreator eine Möglichkeit geboten, eine der Zielgruppen anzunehmen. Die Redakteure erhalten so eine spezifische Sicht auf die Webseite und können auf diesem Weg die von ihnen definierte Personalisierung der Inhalte überprüfen. Ohne diese Möglichkeit würde ihnen immer nur eine allgemeine Ansicht des Inhalts angezeigt und eine Überprüfung wäre nur im Live-Stand möglich.

Um eine der Gruppen anzunehmen, wird in FirstSpirit eine Seitenvorlage benötigt, die ebenfalls alle Zielgruppen für die Redakteure bereitstellt. Innerhalb des mitgelieferten Beispielprojekts wurde dafür auch an dieser Stelle eine Combobox verwendet. Weitere Anforderungen an die Seitenvorlage bestehen nicht.

MPP-Rollen. 

<CMS_INPUT_COMBOBOX name="mpp_roles">
   <CMS_INCLUDE_OPTIONS type="database">
      <LABELS>
         <LABEL lang="*">#item.name</LABEL>
      </LABELS>
      <TABLE>standard.roles</TABLE>
   </CMS_INCLUDE_OPTIONS>
   <LANGINFOS>
      <LANGINFO lang="*" label="Customer Group"/>
   </LANGINFOS>
</CMS_INPUT_COMBOBOX>

Nach der Erzeugung der Seitenvorlage muss die Multi Perspective Preview aktiviert werden. Öffnen Sie dafür den ServerManager und wechseln Sie auf den Bereich Projekt-EigenschaftenOptionen. Selektieren Sie anschließend über den entsprechenden Button die erstellte Seitenvorlage als Vorschau-Parameter (vgl. Abbildung Auswahl der Vorschau-Parameter ). Ein Klick auf den Button OK speichert die vorgenommenen Änderungen.

Auswahl der Vorschau-Parameter
Abbildung 26. Auswahl der Vorschau-Parameter


7.4. Vorschau-Darstellung

Wird im ContentCreator über die Multi Perspective Preview eine Zielgruppe selektiert, ist die Darstellung der Seite entsprechend anzupassen. Dafür muss jedoch zunächst die ausgewählte Gruppe ermittelt werden. Dies kann beispielsweise über die folgende JSP-Abfrage erfolgen:

Abfrage bezüglich der Auswahl einer Zielgruppe. 

$CMS_IF(#global.is("WEBEDIT"))$
   <% if (session.getAttribute("fs.preview.mpp_roles") != null) {
      String role = session.getAttribute("fs.preview.mpp_roles").toString(); %>
      [...]
   <% } %>
$CMS_END_IF$

Diese Abfrage ist nur bis einschließlich FirstSpirit 5.1 einsetzbar. Ab FirstSpirit 5.2 muss über die PreviewParameter.Factory ein PreviewParameter-Objekt erzeugt werden. Mit diesem lassen sich Zeiteinstellungen und weitere Parameter, wie beispielsweise eine ausgewählte Zielgruppe, ermitteln.

Die Abfrage stellt zunächst sicher, dass es sich bei der aktiven Umgebung um den ContentCreator handelt und greift nur dann. Anschließend ermittelt sie die selektierte Zielgruppe, wenn die Auswahl nicht leer ist. Eine Behandlung dieses Zustands und die damit verbundene Anpassung des dargestellten Inhalts muss stets projektspezifisch erfolgen.

Im mitgelieferten Beispielprojekt wird die Anzeige des Inhalts über CSS gesteuert. Dabei sind die spezifischen Inhalte initial ausgeblendet und werden sichtbar, sobald die zugehörige Zielgruppe selektiert wird.

Darstellung über CSS. 

<style type="text/css">
   .$CMS_VALUE(ps_mppCssPrefixRole)$ {display:none;}
   .$CMS_VALUE(ps_mppCssPrefixRole)$<%= role %> {display:block;};
</style>

Die gesamte Abfrage ist im Beispielprojekt innerhalb der Formatvorlage Preview Generation enthalten, die über einen $CMS_RENDER$-Aufruf in der verwendeten Seitenvorlage eingebunden ist.

7.5. Slot Configuration

Beid er Verwendung von Slots müssen die für die Personalisierung definierten Parameter in der Slot Configuration ergänzt werden. Der nachfolgende Code-Ausschnitt zeigt beispielhaft, wie dies erfolgen kann.

Slot Configuration. 

$CMS_SET(set_slotConfig)$ <slot-configuration
      slot-id="cat-banner" ❷
      context="category"
      context-id="$CMS_VALUE(pt_dwre_previewPageId)$" ❸
      configuration-id="$CMS_VALUE("fs_slot_configuration_" + #global.section.id)$"
      default="true"
      assigned-to-site="true">
      <template>slots/content/categorybanner.isml</template>
      <enabled-flag>true</enabled-flag>
      <content>
         <content-assets>
            <content-asset content-id="$CMS_VALUE(set_xml_id)$"/>
         </content-assets>
      </content>
      $CMS_IF(!st_role.isEmpty)$
         <customer-groups>
            <customer-group group-id="$CMS_VALUE(st_role.getValue().id)$"/> </customer-groups>
      $CMS_END_IF$
   </slot-configuration>
$CMS_END_SET$

$CMS_IF(#global.language==#global.project.masterLanguage)$
   $CMS_SET(set_xml_lang,"x-default")$
   $CMS_SET(void,ps_xmlCollectorContentSlot.addXml(null,set_slotConfig.toString(),null))$ ❺
$CMS_END_IF$

Es wird zunächst die Variable set_slotConfig definiert, in der das benötigte XML gespeichert wird.

Innerhalb dieses XMLs wird neben der entsprechenden aus der Commerce Cloud stammenden Slot ID die Context ID angegeben. Letztere wird von den Redakteuren im Formular der Seitenvorlage gespeichert.

Anschließend wird die ID der auswählten Zielgruppe abgefragt. Die Auswahl der Zielgruppe erfolgt durch die Redakteure über die zuvor erstellte Combobox.

Das XML muss abschließend dem passenden XML-Kollektor übergeben werden, der in den Projekteinstellungen initialisiert wird. An dieser Stelle und im Beispielprojekt handelt es sich dabei um den Kollektor ps_xmlCollectorContentSlot. Beim Deployment wird die Konfiguration zur Commerce Cloud übertragen und dort entsprechend übernommen.

Diese Konfiguration ist im Beispielprojekt innerhalb der Absatzvorlage Banner enthalten.

Die Content Integration API bietet eine alternative Möglichkeit personalisierten Inhalt anzuzeigen.

8. Content Integration API

Die Content Integration API bietet eine zusätzliche Möglichkeit, Inhalte aus FirstSpirit in der Commerce Cloud darzustellen. Anders als beim bisher beschriebenen Verfahren werden hierbei Velocity Vorlagen anstelle von Slots genutzt.

Dadurch ändert sich die Rolle, die FirstSpirit bei der Gestaltung einer Seite einnimmt. Im slotbasierten Ansatz wird das Rahmenwerk einer Seite Commerce Cloud-seitig definiert und FirstSpirit ergänzt lediglich an festgelegten Stellen Inhalte. Auch einfache Änderungen am Rahmenwerk erfordern deshalb immer eine Anpassung der Commerce Cloud-Vorlage und der enthaltenen Slots, was durch Redakteure nicht geleistet werden kann. Dieses Problem ist noch gravierender, falls die Änderung nur einzelne Seiten betrifft.

Die Verwendung der Content Integration API versetzt FirstSpirit dagegen in die Lage, vollständige Seiten auszuliefern, wodurch Redakteuren mehr Freiraum bei der strukturellen Gestaltung einer Seite gegeben werden kann. Absätze können sie also in einem projekt- und seitenspezifischen Umfang selbstständig anordnen, ohne dass dafür Vorlagenänderungen vorzunehmen sind.

Des Weiteren können Entwickler die Fähigkeiten Velocitys ausnutzen, um Logik in Vorlagen zu implementieren. Zur Entwicklung eigener Funktionen steht ihnen dabei die Commerce Cloud Script API zur Verfügung. Die programmatischen Möglichkeiten in Vorlagen sind folglich sehr groß und können zum Beispiel genutzt werden, um personalisierten Inhalt in einer Seite darzustellen.

Eine parallele Nutzung des slotbasierten Ansatzes und der Content Integration API ist ohne Einschränkung möglich, weshalb für jede Seite bzw. Seitentyp der passende Ansatz gewählt werden kann.

Dieses Kapitel beschreibt einen Ansatz zur Nutzung der Content Integration API mit FirstSpirit. Neben den Inhalten, die weiterhin in Content Assets gespeichert werden, generiert und veröffentlicht FirstSpirit hierbei Velocity Seitenvorlagen. Die Darstellung einer Seite geschieht über einen speziellen JavaScript Controller, der Content Asset und Velocity Seitenvorlage verbindet.

8.1. Commerce Cloud

Dieses Kapitel beschreibt die Commerce Cloud-seitige Erweiterung, die für die Integration notwendig ist. Dabei handelt es sich um einen JavaScript Controller, der eine spezielle Funktionalität umsetzen muss, darüber hinaus aber projektspezifisch erweitert werden kann.

Des Weiteren wird in diesem Kapitel auf das Thema Caching eingegangen, dessen richtige Konfiguration vor allem für personalisierte Inhalte relevant ist.

8.1.1. JavaScript Controller

Für dieses Kapitel wird angenommen, dass der JavaScript Controller in der Cartridge unter dem Pfad cartridge/controllers/Content.js gespeichert wird.

Der JavaScript Controller soll ein übergebenes Content Asset auslesen und mit Hilfe einer Velocity Seitenvorlage darstellen. Diese Aufgabe lässt sich in vier grundlegende Schritte unterteilen:

  1. Das Content Asset anhand des HTTP-GET-Parameters cid auslesen
  2. Ein Parameter-Objekt erzeugen, das im Velocity Code verwendete Funktionen und Parameter bereitstellt
  3. Den Inhalt des Content Assets mit Hilfe der Velocity Engine rendern
  4. Eine Velocity Seitenvorlage mit dem Inhalt des Content Assets rendern

Diese Schritte sowie ihre Implementierung werden im Folgenden beschrieben.

Der vollständige Quellcode des hier beschriebenen minimalen Controllers ist in Anhang A, JavaScript Controller zu finden.

Die Implementierung des Controllers beschränkt sich bewusst auf seine Kernfunktionalität, um sie einfach und leicht verständlich zu halten. Für einen produktiven Einsatz sollte sie unter anderem um eine Validitätsprüfung der Parameter und eine solide Fehlerbehandlung erweitert werden.

Der JavaScript Controller enthält eine öffentliche Methode Show, die als Einstiegspunkt zum Rendern von Content Assets dient und die Klassen dw.template.Velocity und dw.content.ContentMgr aus der Commerce Cloud Script API verwendet. Das Grundgerüst des Controllers sieht somit wie folgt aus:

"use strict";

var contentManager = require("dw/content/ContentMgr"); var velocity = require('dw/template/Velocity'); ❷

exports.Show = function() { // ...
};

exports.Show.public = true; 

Einbinden der Klasse dw.content.ContentMgr

Einbinden der Klasse dw.template.Velocity

Definition der Methode Show. Ihr Inhalt folgt in den folgenden Abschnitten.

Öffentlichen Zugriff auf die Methode Show ermöglichen

Zum Auslesen des Content Assets wird zunächst der HTTP-GET-Parameter cid ermittelt, dessen Wert dann dem ContentMgr übergeben wird, um das Content Asset auszulesen. Falls ein Redakteur eine neue Seite anlegt, ist der Commerce Cloud noch kein entsprechendes Content Asset bekannt. Um in FirstSpirit trotzdem eine Vorschau für die neue Seite zu ermöglichen, wird in diesem Fall ein temporäres Objekt anstelle des Content Assets verwendet, das ein leeres Asset imitiert.

var contentAssetId = request.getHttpParameterMap().get("cid"); var contentAsset = contentManager.getContent(contentAssetId) ❷
                || { custom: { body: "" }, template: "welcome_page.vs" }; 

Auslesen des HTTP-GET-Parameters cid

Abfrage des Content Assets

Definition eines leeren Dummy-Assets, falls kein Content Asset mit der übergebenen Id gefunden wurde

Anschließend wird ein Objekt mit dem Namen global definiert. Mit diesem Objekt wird der Velocity Engine eine spezialisierte API bereitgestellt, deren Funktionen und Eigenschaften in der verarbeiteten Velocity Seitenvorlage nutzbar sind. Struktur und Inhalt dieses Objektes müssen projekt- und seitenspezifisch definiert und implementiert werden. Denkbar sind zum Beispiel Funktionen, die unter einem sprechenden Namen verschiedene Widgets einbinden.

var global = {
    ❶
};

Projekt- und seitenspezifische Eigenschaften und Funktionen

Die Eigenschaft body speichert den Inhalt des Content Assets und muss beim hier beschriebenen Ansatz immer in irgendeiner Form im global-Objekt vorhanden sein. Da der Inhalt des Assets selbst Velocity Code enthalten kann, wird dieser zunächst über die Velocity Engine interpretiert und das Ergebnis in body gespeichert. Beim Rendern des Content Assets kann der Velocity Engine ein separates Parameter-Objekt zur Verfügung gestellt werden. Genauso ist es aber möglich, global wieder zu verwenden.

function render(content, parameters) {
    var writer = new dw.io.StringWriter();
    velocity.render(content, parameters, writer)
    return writer.toString();
}

// ...

global.body = render(contentAsset.custom.body, global);

Abschließend wird die am Content Asset hinterlegte Velocity Seitenvorlage gerendert und das Ergebnis dem Aufrufer angezeigt. Als Parameter-Objekt wird das zuvor erstellte Objekt global übergeben.

velocity.renderTemplate(contentAsset.template, global);

8.1.2. Caching

Die Commerce Cloud bietet viele Möglichkeiten Seiten zu cachen und so schnelle Antwortzeiten zu gewährleisten. Falls eine Seite kunden- oder sessionabhängige Informationen enthält und das Caching nicht richtig konfiguriert ist, kann es jedoch schnell zu unerwarteten Ergebnissen kommen.

Aufbauend auf den Erläuterungen des Kapitels JavaScript Controller wird im Folgenden anhand eines konkreteren Beispiels ein Ansatz erläutert, der ein korrektes Ergebnis sicherstellt.

Anzuzeigen ist eine aus vier Blöcken bestehende Seite. Bei diesen Blöcken handelt es sich um

  1. einen Banner, der für weibliche Kunden speziellen Inhalt anzeigt,
  2. einen Header, der kundenspezifische Informationen darstellt,
  3. den Inhalt des Content Assets und
  4. einen allgemeinen Footer.

Diese Blöcke bieten unterschiedliches Potential gecacht zu werden.

Der Banner ist lediglich abhängig vom Geschlecht des Kunden. Das heißt, dass alle Kunden in zwei Gruppen unterteilt werden können: weibliche und männliche Kunden. Innerhalb einer Gruppe ist der Inhalt für alle Kunden identisch, wohingegen Kunden verschiedener Gruppen verschiedene Inhalte sehen. Aus diesem Grund kann der Inhalt für beide Gruppen getrennt und für einen längeren Zeitraum gecacht werden. Allerdings muss bei jedem Seitenaufruf das Geschlecht des Kunden ausgewertet werden, um den richtigen Cache anzusprechen.

Der Header enthält Informationen, die abhängig von jedem einzelnen Kunden sind, wie zum Beispiel seinen Namen. Für diese Komponente muss das Caching also pro Kunde erfolgen. Die Gültigkeit des Caches kann dabei kurz gehalten werden, da die kundenspezifischen Inhalte im Vergleich zu allgemeinen Inhalten seltener und für kürzere Zeit benötigt werden.

Der Footer wird nicht personalisiert und kann deshalb für alle Kunden und für einen langen Zeitraum gecacht werden.

Der Inhalt des Content Assets kann selbst Velocity Code enthalten, weshalb er getrennt betrachtet werden muss. Allerdings gelten für ihn die gleichen Überlegungen, weshalb auf ihn nicht weiter eingegangen wird.

Die einzelnen Komponenten stellen unterschiedliche Anforderungen an das Caching, weshalb es sinnvoll ist, jede in einem separaten Widget zu kapseln, sodass für jedes das Caching einzeln gesteuert werden kann. Da das Commerce Cloud-Caching auf URLs basiert und einem Widget Parameter über seine Anfrage-URL übergeben werden, kann das Caching der Widgets über Parameter gesteuert werden. Für das Banner-Widget ist beispielsweise ein Parameter isFemale sinnvoll, der einen boolschen Wert enthält. Es sind also zwei gültige URLs denkbar, was zu zwei Caches für das Widget führt: Einer für weibliche und einer für männliche Kunden. Genauso kann für das Header-Widget ein Parameter id definiert werden, in dem die Id des Kunden abgelegt wird. Dadurch wird der spezifische Inhalt für jeden Kunden einzeln vorgehalten.

Die einzelnen Widgets werden dann beim Rendern der initial aufgerufenen Seite über Remote Includes integriert. Das vollständig zusammengesetzte Ergebnis dieser Seite kann ebenfalls gecacht werden, wodurch die Einstellungen der einzelnen Widgets ausgehebelt werden würden und es doch zu unerwarteten Ergebnissen käme. Deshalb ist es wichtig, diese Antwort nicht zu cachen. Folglich wird die angeforderte Seite also bei jedem Aufruf neu zusammengebaut, die einzelnen Komponenten jedoch durch ihr individuelles Caching wiederverwendet.

Realisiert wird dies über den JavaScript Controller und das Parameter-Objekt global, welches er der Velocity Engine bereitstellt. Das global-Objekt enthält in diesem Beispiel die parameterlosen Funktionen include.banner(), include.header() und include.footer(), die an den passenden Stellen in der Velocity Seitenvorlage aufgerufen werden. Des Weiteren beinhaltet es wie bisher die Eigenschaft body, die den Inhalt des Content Assets speichert. Innerhalb der include-Funktionen werden die jeweiligen Widgets über passend parametrisierte Velocity.remoteInclude-Aufrufe in die Seite integriert. Der initial aufgerufene JavaScript Controller, der das global-Objekt erzeugt und das Rendern der Velocity Seitenvorlage anstößt, darf wie angesprochen nicht gecacht werden, damit er bei jedem Seitenaufruf ausgeführt wird und die Caching-Einstellungen der einzelnen Widgets nicht umgangen werden. Dies ist das Standard-Verhalten, weshalb kein zusätzlicher Code notwendig ist.

Das Zusammenspiel zwischen Velocity Seitenvorlage, Parameter-Objekt und Widgets ist in Abbildung Caching Beispiel dargestellt.

Caching Beispiel
Abbildung 27. Caching Beispiel


8.2. FirstSpirit

Dieses Kapitel beschreibt die FirstSpirit-seitigen Erweiterungen, die für die Integration notwendig sind.

8.2.1. Velocity Seitenvorlage

Die verwendete Velocity Seitenvorlage wird in FirstSpirit gepflegt und an die Commerce Cloud übertragen. Dazu ist in FirstSpirit zunächst eine Seitenvorlage anzulegen, deren Ausgabekanal für dieses Beispiel folgenden Inhalt hat:

<!DOCTYPE html>
<html>
    <body>
        <!-- CMS-PREVIEW-CONTENT-START --> ❶
        $body <!-- CMS-PREVIEW-CONTENT-END --> </body>
</html>

Diese HTML-Kommentare werden benötigt, um später die Vorschau in FirstSpirit zu generieren.

An dieser Stelle wird der Inhalt des Content Assets eingebunden. Der Parameter body wurde in Kapitel JavaScript Controller definiert.

Die Ziel Extension der Seitenvorlage muss im Reiter Eigenschaften auf vs gesetzt werden.

Auf Basis dieser neuen Seitenvorlage muss anschließend jeweils genau eine Seite und eine Seitenreferenz angelegt werden. Dabei sollte zumindest die Seitenreferenz in einem separaten Ordner auf der obersten Ebene der Struktur platziert werden, um die spätere Übertragung der Velocity Seitenvorlage zur Commerce Cloud zu vereinfachen.

8.2.2. Auftrag

Die Velocity Seitenvorlage wird nach der Freigabe der in Kapitel Velocity Seitenvorlage erzeugten Objekte von FirstSpirit generiert. Zur Übertragung zur Commerce Cloud muss der in Kapitel Deployment-Auftrag beschriebene Auftrag um ein weiteres WebDAV-Deployment erweitert werden. Dies geschieht am einfachsten, indem eine Kopie der Aktion aus Kapitel WebDAV-Deployment erzeugt und angepasst wird. Folgende Parameter sind zu überarbeiten:

url
Die URL ist auf folgenden Wert zu setzen:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Dynamic/<SITE ID>
srcprefix
Für diesen Parameter muss der Pfad zum Strukturordner, in dem die Seitenreferenz für die Velocity Seitenvorlage abgelegt wurde, relativ zum Root-Knoten des Generierungsverzeichnisses angegeben werden. Also z.B. en/velocity_templates.

Alle sonstigen Parameter können übernommen werden.

8.2.3. Seitenvorlage für redaktionelle Inhalte

Da dieser Ansatz zur Nutzung der Content Integration API weiterhin Content Assets erzeugt, gelten für Seitenvorlagen für redaktionelle Inhalte alle Überlegungen aus Kapitel Seitenvorlage. Es sind lediglich zwei spezifische Anpassungen vorzunehmen.

Zum einen muss das Attribut template am Content Asset gepflegt sein, da dieses im JavaScript Controller herangezogen wird, um die richtige Velocity Seitenvorlage zu ermitteln.

Der JavaScript Controller kann natürlich so entwickelt werden, dass er eine Default-Velocity-Seitenvorlage auswählt, falls am Content Asset keine hinterlegt ist.

Des Weiteren muss für alle neuen Seitenvorlagen ein neuer Page Type definiert werden, damit die für die Vorschau generierte URL den richtigen JavaScript Controller-Aufruf enthält. Konkret muss also die Variable pt_dwre_previewType auf einen neuen Wert gesetzt werden. Für das Beispiel dieses Kapitels wird dafür content benutzt.

8.2.4. Vorlage Create Preview URL

Die in der Auslieferung enthaltene Formatvorlage Create Preview URL muss um einen weiteren Fall erweitert werden, damit die Vorschau für Seiten, die die Content Integration API nutzen, korrekt funktioniert.

Der verwendete Vergleichswert hängt vom neuen Page Type ab, der in der Seitenvorlage aus Kapitel Seitenvorlage für redaktionelle Inhalte verwendet wurde.

Entsprechend hängt die aufgerufene URL vom Namen des Controllers, der aufzurufenden Methode sowie der benötigten Parameter ab (siehe Kapitel JavaScript Controller).

In diesem Beispiel wäre der neue Eintrag in der Vorlage Create Preview URL also:

$CMS_CASE("content")$Content-Show?cid=$CMS_VALUE(pageId)$

8.2.5. Widgets

Eingangs wurde bereits darauf hingewiesen, dass mit der Content Integration API Redakteuren mehr Möglichkeiten bei der Gestaltung einer Seite gegeben werden können. Visuelle Komponenten, die ein Redakteur auf einer Seite platzieren und anordnen können soll, werden Commerce Cloud-seitig am besten als Widget implementiert. Auf Seiten FirstSpirits bietet es sich dann an, für jedes Widget eine Absatzvorlage zu definieren.

Innerhalb des Ausgabekanals einer solchen Vorlage muss zwischen Vorschau und Nicht-Vorschau unterschieden werden. Für die Vorschau wird die Anfrage-URL des Widgets bestimmt. Diese URL wird dann dem Skript include_html übergeben, welches Teil der Auslieferung ist. In diesem Skript wird die URL aufgerufen und das Ergebnis in die generierte Seite eingefügt.

Damit ein Widget so über das Internet abgerufen werden kann, muss der öffentliche Zugriff auf das Widget gestattet sein.

Für die Generierung des Content Assets wird stattdessen lediglich ein Velocity-Aufruf erzeugt. Welche Funktion aufgerufen wird und welche Parameter sie erwartet, hängt vom Parameter-Objekt ab, welches im JavaScript Controller definiert und der Velocity Engine beim Rendern des Content Assets übergeben wird.

Ein generalisiertes Beispiel ist in Listing Ausgabekanal einer Absatzvorlage eines Widgets zu sehen. Zum Einbetten des Widgets wird eine allgemeine Funktion verwendet, die den Namen des Widgets und die benötigten Parameter entgegennimmt.

Beim Referenzieren von Widgets sollte Augenmerk auf deren Caching gelegt werden.

Ausgabekanal einer Absatzvorlage eines Widgets. 

$CMS_IF(#global.isPreview)$
    <div $CMS_VALUE(editorId())$ >
        $CMS_SET(set_includeURL, ps_dwProtocol + ps_dwInstance + ".demandware.net/on/demandware.store/")$
        $CMS_SET(set_includeURL, set_includeURL + "Sites-" + ps_dwSiteId + "-Site/")$
        $CMS_SET(set_includeURL, set_includeURL + #global.language.abbreviation + "/")$ ❶
        $CMS_SET(set_includeURL, set_includeURL + <ACTION> + <PARAMETER>)$

        $CMS_RENDER(script:"include_html", includeURL:set_includeURL.toString())$
    </div>
$CMS_ELSE$
    $include.widget("<ACTION>", <PARAMETER>)
$CMS_END_IF$

Als Sprache wird die Abkürzung der aktuell generierten FirstSpirit-Sprache verwendet. Bei Bedarf muss hier ein eigenes Mapping auf eine Commerce Cloud-Locale implementiert werden.

8.3. Personalisierung

Mit der Content Integration API kann Shop-Besuchern personalisierter Inhalt dargestellt werden, ohne dazu auf Slot Configurations zurückzugreifen.

Stattdessen kann die Personalisierung über Velocity in Kombination mit der Commerce Cloud Script API erfolgen. Abhängig von den konkreten Projektanforderungen können dabei verschiedene Ansätze und Implementierungen verfolgt werden.

Eine simple Umsetzung nutzt im Content Asset eine if-else-Verzweigung, die verschiedene Personalisierungs-Fälle abbildet und so nur der passende Inhalt dargestellt wird. Der entsprechende Abschnitt im body des Content Assets sieht dann wie folgt aus:

#if ($customer.isInGroup('Big Spenders'))
    <!-- Content for Big Spenders -->
#elseif ($now.isBetween('2016-10-01', '2016-11-01'))
    <!-- Content for all other customers during October 2016 -->
#else
    <!-- Content in all other cases -->
#end

In diesem Beispiel wird Kunden der Gruppe Big Spenders spezieller Inhalt dargestellt. Genauso wie allen anderen Kunden im Zeitraum vom 01.10.2016 zum 01.11.2016. Abschließend wird der Inhalt für sonstige Kunden außerhalb dieses Zeitraumes definiert.

Die genutzten Funktionen $customer und $now werden im Parameter-Objekt definiert, welches der Velocity Engine im JavaScript Controller übergeben wird (vgl. JavaScript Controller). Ihre Implementierung nutzt die Commerce Cloud Script API.

Die Nutzung der Content Integration API hat keinen Einfluss darauf, wie die Personalisierung für die Vorschau in FirstSpirit umgesetzt wird.

A. JavaScript Controller

Die Implementierung des Controllers beschränkt sich bewusst auf seine Kernfunktionalität, um sie einfach und leicht verständlich zu halten. Für einen produktiven Einsatz sollte er z.B. um eine Validitätsprüfung der Parameter und eine solide Fehlerbehandlung erweitert werden.

Vollständiger JavaScript Controller

"use strict";

var contentManager = require("dw/content/ContentMgr");
var velocity = require('dw/template/Velocity');

function render(content, parameters) {
    var writer = new dw.io.StringWriter();
    velocity.render(content, parameters, writer)
    return writer.toString();
}

exports.Show = function() {
    var contentAssetId = request.getHttpParameterMap().get("cid");
    var contentAsset = contentManager.getContent(contentAssetId)
                    || { custom: { body: "" }, template: "welcome_page.vs" };

    var global = {
        // ...
    };

    global.body = render(contentAsset.custom.body, global);
    velocity.renderTemplate(contentAsset.template, global);
};

exports.Show.public = true;

9. Rechtliche Hinweise

ContentConnect ist ein Produkt der e-Spirit AG, Dortmund, Germany.
Für die Verwendung des Modules gilt gegenüber dem Anwender nur die mit der e-Spirit AG vereinbarte Lizenz.